Manager API

Epiphany provides a set of static Manager classes as a public API, allowing other mods to interact with the system through Java code.

TIP

All Manager method player parameters are ServerPlayer.

INFO

KubeJS scripts also support the Manager API. See the KubeJS Compat section for details.

AptitudeManager

Manages player aptitude values and Insight Points.

Query Methods

// Get the player's current aptitude value
long getAptitude(ServerPlayer player)

// Get the player's current Insight Points
int getInsightPoints(ServerPlayer player)

// Get the total Insight Points the player has spent
int getTotalInsightPointsSpent(ServerPlayer player)

// Get the aptitude threshold for the player's next Insight Point
long getRequiredForNextPoint(ServerPlayer player)

Mutation Methods

// Set aptitude value (clamped to current cap)
// Fires AptitudeChangedEvent
void setAptitude(ServerPlayer player, long value)

// Add aptitude. Excess automatically converts to Insight Points
// Fires AptitudeChangedEvent, AptitudeLevelUpEvent, InsightPointsChangedEvent
void addAptitude(ServerPlayer player, long amount)

// Add aptitude after applying aptitude_gain_multiplier (base + modifiers)
// The scaled amount is rounded down; zero or negative results are ignored
void addAptitudeWithMultiplier(ServerPlayer player, long amount)

// Set Insight Points count (clamped to >= 0)
// Fires InsightPointsChangedEvent
void setInsightPoints(ServerPlayer player, int value)

// Add to the player's Insight Points (the result is clamped to >= 0)
// Fires InsightPointsChangedEvent
void addInsightPoints(ServerPlayer player, int amount)

// Add exactly enough aptitude to reach the next Insight Point threshold
// Uses addAptitude, so the normal aptitude and level-up events fire
// Returns the amount of aptitude actually added, or 0 if already at/above the threshold
long fillAptitude(ServerPlayer player)

EpiphanyDataUtils

Provides reusable cross-subsystem data operations for Java callers, UI code, and command implementations.

Event behavior

The reset methods intentionally fire no aptitude, Insight Point, or selection events. This matches the behavior of the corresponding /epiphany reset commands.

// Remove all applied Module, Insight, and selected Epiphany rewards
void removeAllRewards(ServerPlayer player)

// Calculate the Insight Point refund for selected Modules and unlocked Insights
// Pure read: does not modify player data
int refundInsightCosts(ServerPlayer player, PlayerEpiphanyData data)

// Remove all rewards and player Epiphany data, then restore SELECTABLE entries
// Equivalent to /epiphany reset all
void resetAll(ServerPlayer player)

// Clear selections and rewards while preserving aptitude
// Refunds selected Module and unlocked Insight costs, then restores SELECTABLE entries
// Equivalent to /epiphany reset select
void resetSelections(ServerPlayer player)

ModuleManager

Manages player module data.

Query Methods

// Whether the module is unlocked (can be selected)
boolean isUnlocked(ServerPlayer player, ResourceLocation moduleId)

// Whether the module is currently selected
boolean isSelected(ServerPlayer player, ResourceLocation moduleId)

// Whether the module is completed
boolean isCompleted(ServerPlayer player, ResourceLocation moduleId)

// Number of modules the player currently has selected
int getSelectedModuleCount(ServerPlayer player)

// Configured hard cap on simultaneously selected modules
int getMaxSelectedModules()

Mutation Methods

// Set module unlock state
// Fires ModuleUnlockEvent (Pre) and ModuleUnlockedEvent (Post)
void setUnlocked(ServerPlayer player, ResourceLocation moduleId, boolean unlocked)

// Select a module (consumes Insight Points, checks conditions and cap)
// Fires ModuleSelectEvent (Pre) and ModuleSelectedEvent (Post)
// Applies on_select_reward
void select(ServerPlayer player, ResourceLocation moduleId)

// Complete a module (checks if all insights are unlocked, grants Epiphany Slot)
// Fires ModuleCompleteEvent (Pre) and ModuleCompletedEvent (Post)
// Applies on_complete_reward
void complete(ServerPlayer player, ResourceLocation moduleId)

// Force-select (ignores cost and conditions)
// Fires ModuleSelectedEvent (Post)
void forceSelect(ServerPlayer player, ResourceLocation moduleId)

// Force-complete (ignores insight check, grants Epiphany Slot)
// Fires ModuleCompletedEvent (Post)
void forceComplete(ServerPlayer player, ResourceLocation moduleId)

// Reset module (refunds Insight Points, removes rewards)
void resetModule(ServerPlayer player, ResourceLocation moduleId)

// Auto-unlock locked modules whose conditions are met
// skipEventDriven: whether to skip polling
// silent: whether to fire notification messages in NotificationListener
void checkAutoUnlock(ServerPlayer player, boolean skipEventDriven, boolean silent)

// Clean up module data for registry entries that no longer exist
void cleanupOrphanedData(ServerPlayer player)

InsightManager

Manages player insight state.

Query Methods

// Whether the insight has been unlocked
boolean isSelected(ServerPlayer player, ResourceLocation insightId)

// Whether the insight's owning module is selected
boolean isModuleSelected(ServerPlayer player, ResourceLocation insightId)

Mutation Methods

// Unlock an insight (consumes Insight Points, checks prerequisites)
// Fires InsightSelectEvent (Pre) and InsightSelectedEvent (Post)
void select(ServerPlayer player, ResourceLocation insightId, ResourceLocation moduleId)

// Force-unlock an insight (ignores cost and prerequisites)
void forceSelect(ServerPlayer player, ResourceLocation insightId, ResourceLocation moduleId)

// Reset an insight (refunds Insight Points, removes rewards)
void resetInsight(ServerPlayer player, ResourceLocation insightId)

EpiphanyManager

Manages player epiphany state.

Query Methods

// Whether the epiphany is unlocked (can be selected)
boolean isUnlocked(ServerPlayer player, ResourceLocation epiphanyId)

// Whether the epiphany is currently selected
boolean isSelected(ServerPlayer player, ResourceLocation epiphanyId)

// Number of Epiphany Slots the player has unlocked
int getEpiphanySlots(ServerPlayer player)

// Number of Epiphany Slots currently occupied
int getUsedEpiphanySlots(ServerPlayer player)

// Configured hard cap on selectable Epiphanies
int getMaxEpiphanySlots()

Mutation Methods

// Set epiphany unlock state
void setUnlocked(ServerPlayer player, ResourceLocation epiphanyId, boolean unlocked)

// Select an epiphany (checks slots and conditions)
// Fires EpiphanySelectEvent (Pre) and EpiphanySelectedEvent (Post)
void select(ServerPlayer player, ResourceLocation epiphanyId)

// Force-select (ignores slots and conditions)
void forceSelect(ServerPlayer player, ResourceLocation epiphanyId)

// Reset an epiphany
void resetEpiphany(ServerPlayer player, ResourceLocation epiphanyId)

// Clean up epiphany data for registry entries that no longer exist
void cleanupOrphanedData(ServerPlayer player)

// Auto-unlock locked epiphanies whose conditions are met
// skipEventDriven: whether to skip polling
// silent: whether to fire notification messages in NotificationListener
void checkAutoUnlock(ServerPlayer player, boolean skipEventDriven, boolean silent)

AptitudeSourceManager

Resolves datapack-defined aptitude sources and grants their rewards.

// Resolve one behavior and target without modifying player data
// Returns the matched reward and related resolution details
AptitudeSourceResolver.Resolution resolve(
    ServerPlayer sp, ResourceLocation behaviorId,
    ResourceLocation targetId, @Nullable Registry<?> registry)

// Grant aptitude
// behaviorId: behavior ID (e.g., "mymod:foo")
// targetId: target ID (e.g., the entity type that was killed)
// registry: the registry targetId belongs to, used for tag lookup. Can be null
boolean grant(
    ServerPlayer sp, ResourceLocation behaviorId,
    ResourceLocation targetId, @Nullable Registry<?> registry)

Usage example:

@SubscribeEvent
static void onCustomMobKill(LivingDeathEvent event) {
    if (!(event.getSource().getEntity() instanceof ServerPlayer sp)) return;
    ResourceLocation targetId = BuiltInRegistries.ENTITY_TYPE.getKey(event.getEntity().getType());
    AptitudeSourceManager.grant(
        sp,
        ResourceLocation.fromNamespaceAndPath("mymod", "custom_kill"),
        targetId,
        BuiltInRegistries.ENTITY_TYPE
    );
}

AptitudeFormula

Aptitude calculation utility class. Currently only supports linear calculation; more formula types are planned.

Formula:

$$\text{required} = \text{Config.baseAptitudeCap} + (\text{totalSpent} + \text{insightPoints}) \times \text{Config.aptitudeCapGrowth}$$

// Calculate the aptitude required for the next Insight Point
// totalSpent: total Insight Points spent
// insightPoints: currently available Insight Points
// Returns: required aptitude value
long calcRequiredAptitude(long totalSpent, int insightPoints)